home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-04
/
tldr20.zip
/
FILXRF.DOC
< prev
next >
Wrap
Text File
|
1992-10-01
|
22KB
|
571 lines
F i l e X r e f
Version 2.0
────────────────────────
User's Guide
┌───────┐
┌───────┐ │ (R)
──│ │ │───────────────────
│ ┌───────┐ │ Association of
ConVal Software, Inc. │ │ │─┘ Shareware
└──│ o │ Professionals
─────│ | │─────────────────────
└───┴───┘ MEMBER
F i l e X r e f
Version 2.0
────────────────────────
User's Guide
┌───────┐
┌───────┐ │ (R)
──│ │ │───────────────────
│ ┌───────┐ │ Association of
ConVal Software, Inc. │ │ │─┘ Shareware
└──│ o │ Professionals
─────│ | │─────────────────────
└───┴───┘ MEMBER
Copyright 1990-1992 ConVal Software, Inc.
All rights reserved.
This program is produced by a member of the Association of Shareware
Professionals (ASP). ASP wants to make sure that the shareware principle
works for you. If you are unable to resolve a shareware-related problem with
an ASP member by contacting the member directly, ASP may be able to help.
The ASP Ombudsman can help you resolve a dispute or problem with an ASP
member, but does not provide technical support for members' products.
Please write to the ASP Ombudsman at:
ASP Ombudsman
545 Grover Road
Muskegon, MI 49442-9427
U.S.A.
or send a CompuServe message via CompuServe MAIL to ASP Ombudsman
70007,3536.
The ombudsman may be contacted by FAX by sending to the ASP FAX number:
(616) 788-2765. In communication with the ombudsman please include a
telephone number and/or FAX if available.
TABLE OF CONTENTS
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Features of FileXref . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Specifying the Files to be Examined. . . . . . . . . . . . . . . . . . . 9
Specifying Words to Search for . . . . . . . . . . . . . . . . . . . . . 10
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Notes and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 13
Data File Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Page 6
Introduction
──────────────────────────────────────
ConVal Software supports software developers. It provides tools and services
to assist throughout the life cycle of a software project.
FileXref was the first of these tools, and I think you'll find it can give
you a competitive edge for your software projects.
There are three questions that FileXref directly answers.
What is the potential application-wide impact of changing a particular
source file?
When I'm fixing a bug, how can I be sure that I've addressed the whole
class of the underlying problem and not just one instance?
What files are unused and obsolete?
These questions can't be answered without some groundwork on your part,
however. (Isn't that always the case?)
FileXref examines text file representations of the components of your
application. This can include source code as well as your documentation
files, program specs, etc. It needs your files to follow minimum naming
conventions. For example, file extensions must indicate the type of data
held in the file. So .C files imply C source code, while .BAT files imply
batch files, and .TXT or .DOC implies a printable text file. It doesn't
really matter what the extension is, as long as all files with the same
extension are the same type of file.
Although it is not a requirement for FileXref, you will reduce your own
analysis efforts if you:
■ never let variable names match any of your filenames, language
keywords or words you may use in messages to the user,
■ make your filenames unique across all the file types you use, and
■ group files of the same file type under a common subdirectory
To state this differently, when you want to find something you want only to
find what you're looking for. So if you name a variable "help", and have
files with the name "help" and use the word help in messages, you will
complicate your life. Why? Well when you are having a problem with the
variable named "help" not being properly initialized, the first thing you'll
probably do is a global search for the word "help". What comes back from
the search will be far more than you need to solve the immediate problem.
So you'll have to waste your time looking at files having nothing to do with
the problem you're solving. Wouldn't it be easier if your search returned
just references to the variable?
To see how FileXref works independently of ToolDriver, type FILEXREF at the
DOS command line. This will cross reference the files in FILEXREF.FSL and
the words in FILEXREF.WSL.
Page 7
A Condensed File Cross Reference report, showing the relationships of the
files will be produced. A Condensed Word Usage Report will also be created
if the text file FILEXREF.WSL exists. An Unreferenced Files will be produced
if there were any files which were not referenced by any others in the list.
View the output report FILEXREF.RPT and the run statistics FILEXREF.MSG.
Features of FileXref
──────────────────────────────────────
FileXref analyzes a list of text files, extracting cross reference
information which it stores in memory. It can process all text files and
this version has special processing logic for supporting the syntax of the
following file types:
FILE
EXTENSION CATEGORY
───────────────────────────────────────────────
.BAS BASIC
.BAT Batch Files
.C .CPP C and
.H .HPP C++ source
.CBL COBOL
.COB COBOL
.FOR FORTRAN
.ASM Macro Assembler
.MAK Make files
.PAS Pascal
.PLI PL/I
.REX REXX
.SQL .INP Oracle
.TXT .DOC Text (ASCII)
.PRG xBASE
───────────────────────────────────────────────
All other types are scanned as if they were ASCII text files with no
regard to whether a reference was found in a "comment".
You will prepare the list of files to be examined and insure that it
represents all files related to your application. Or, you may use a utility,
FileList (see Page 10), to create a list of all files on a disk drive which
match one of the file types in the table just above.
You'll optionally prepare a list of words and/or word prefixes you'd also
like cross referenced.
Page 8
FileXref can run out of memory when processing very large numbers of files
and words. If this happens, you may unload other programs (like TSR's),
and/or use your text editor to pare down the list generated by FileList to
just those files needed by your application. You may also need to reduce the
list of words and word prefixes you supplied. Later you'll see how to break
a large job into smaller pieces.
FileXref will generate report files containing cross reference information
for the list of files and words provided.
Three report files may be produced:
1) The file cross reference report presents "up" and "down" references in
one integrated report. It lists a file name in the center column with
its "next assembly" information on the left and its "component"
information on the right.
The cross reference report may be selected in two styles:
Use "condensed" reporting style when knowing a file's file type is
enough to know the directory where it may be found.
Use "extended" reporting when filenames are not enough to uniquely
determine a full file specification.
E.G If C:\APP01\HIST.PRG and C:\APP01\HIST.C both exist, then a
reference to HIST alone is ambiguous.
This report will tell you the global impact of changing a file. By
examining the list of impacted files repeatedly, you can construct a
completely exploded tree representing the "ripple effect" of changing
the one file.
2) The Word Usage Report is optional. It shows the usage of names,
symbols, and variables throughout your source and documentation files.
If you supply a list of words or word prefixes to FileXref, it will
cross reference the words and word prefixes to the files referencing
them. This report also is available in condensed and extended styles.
3) The List of Unreferenced Files lists every file which was referenced by
no other file examined. So this list contains your application's top
level components. You would expect to see top level overview specs
and/or batch files in this list. It also will contain components not
yet documented. This will assist you in keeping documentation up to
date with the product.
And it may contain obsolete components. Now you have a tool to keep
obsolete components from confusing the development and maintenance
effort!
Page 9
By using the following guidelines, the Word Usage Report can be a valuable
aid to problem solving.
■ use meaningful names for variables
■ use the same name for the same variable in all places
■ avoid the use of names which are the same as keywords in any of the
languages you're using
So if you are working on a bug having to do with the value of a counter, the
report will show you every reference to the counter variable in the system -
including documentation and support files! You will be able to address the
counter's integrity throughout the system instead of just in the particular
instance where it was incorrectly set. Here, then, is a tool for solving
problems, not just addressing individual symptoms!
As an alternative to producing report files, FileXref can instead generate
cross reference data (or export) files. These files are in a "quote and
comma delimited" format. You may load these files into your spreadsheet or
database program and work with the data that way.
Specifying the Files to be Examined
──────────────────────────────────────
A File Specification List (FSL) file identifies to FileXref the files to be
scanned and cross referenced. It is a text file and may be created with
any text editor. Each file spec must start in column one of a line and
only one file spec may exist on each line.
Example:
C:\SOURCE\MAINPGM.C
C:\SOURCE\SUBPGM1.C
C:\SOURCE\SUBPGM2.C
C:\SOURCE\INCLUDE\INFILE.H
C:\SOURCE\INCLUDE\OUTFILE.H
A:\SAMPLES\DEMO01.TXT
By naming all files in your application for FileXref, you insure that you
will get a complete cross referencing.
Page 10
To ease the effort in preparing this file, a utility called FileList is
provided for you. Given a starting directory, it will read all file names in
that directory, writing each filename matching a file type in the table on
page 7. FileList processes subdirectories as well so the file selection
process examines a directory tree, not just a single directory.
Example 1: This causes FileList to create an input file for FileXref of
files on C:\SOURCE and its subdirectories, writing it to
file FILEXREF.FSL.
FILELIST C:\SOURCE FILEXREF.FSL
Example 2: This causes FileList to create an input file for FileXref of
files on the C disk.
FILELIST C: FILEXREF.FSL
Example 3: This causes FileList to create an input file for FileXref of
files on the C, D, and E disks.
FILELIST C: C.LST
FILELIST D: D.LST
FILELIST E: E.LST
COPY C.LST+D.LST+E.LST FILEXREF.FSL
Specifying Words to Search for
──────────────────────────────────────
An optional input to FileXref is a Word Specification List (WSL) file. This
contains words and word prefixes you wish to see cross referenced to the
files that reference them. It may also contain words to be excluded from the
resulting list (for example, language keywords).
Use a text editor to create this file. Start each entry in column one and
place a code and a word or word prefix on each line. The code must be "I"
for Include or "X" for eXclude. Terminate word prefixes with an "*".
Example 1: Cross reference all uses of "malloc", "extern" and words that
start with the letters "str". Exclude "strcopy".
I malloc
I extern
I str*
X strcopy
Page 11
Example 2: Cross reference all words.
I *
NOTE: This option will use up memory very quickly, since ALL words
will be cross referenced (even words like "the", "and", "a"). If
you use this option you may need to limit the number of files to
examine, or use the technique in the next example.
Example 3: Cross reference a portion of the alphabet on one pass of the
files. Use multiple passes to cover the whole alphabet. You may
use this technique if you get an "out of memory" type of error
message.
I A*
I B*
I C*
I D*
.
.
.
Getting Started
──────────────────────────────────────
Prior to running FileXref, create the list of files to be examined (see page
9) and, optionally, the list of words and word prefixes to be cross
referenced (see page 10). The program requires that CONFIG.SYS
contain FILES=20, or greater.
The usual way to start up FileXref is to type FILEXREF and press Enter at
the DOS prompt. However, the following parameters can be specified on the
command line to modify FileXref's behavior during a particular run. The
general command line syntax for running FileXref is:
FILEXREF [opt fsl xrf fei msg wsl rpt]
where opt is: ? Causes FileXref to display help information.
/RPTC Tells FileXref to create condensed reports. (This
is the default)
/RPTE Instructs FileXref to create extended reports.
/RPTX Specifies that no reports are to be generated -
produce export files instead.
fsl is a file specification for the input file containing file
specifications of each text file to be examined. If
omitted, this defaults to FILEXREF.FSL.
xrf is a file specification for the output cross reference data
file. If omitted, this defaults to FILEXREF.XRF.
Page 12
fei is a file specification for the output data file to contain a
list of unreferenced files (File End Items). If omitted, this
defaults to FILEXREF.FEI.
msg is a file specification for the output file of run
statistics. If omitted, this defaults to FILEXREF.MSG.
wsl is a file specification for the input file containing the
words and word prefixes to be cross referenced. If omitted,
this defaults to FILEXREF.WSL. If this parameter is not
overridden and the file FILEXREF.WSL exists, then a Word
Usage Report will be generated.
rpt is a file specification for the output file containing the
reports. If omitted, FILEXREF.RPT.
Example 1: Take all the defaults.
FILEXREF
This will read file specifications from FILEXREF.FSL and look for the file
FILEXREF.WSL. If found, it will read its contents for words to be cross
referenced. Messages will be written to FILEXREF.MSG. Since the default
processing is /RPTC, condensed reports will be written to FILEXREF.RPT.
Files FILEXREF.XRF and FILEXREF.FEI will be empty - they are only used
with the /RPTX option.
Example 2: Create data files instead of report files.
FILEXREF /RPTX
This invocation will cause cross reference data (in quote and
comma delimited format) to be written to FILEXREF.XRF and
unreferenced words to be written to FILEXREF.FEI. The report file
FILEXREF.RPT will be empty.
Example 3: Override the location and naming of the report file.
FILEXREF /RPTC FILEXREF.FSL FILEXREF.XRF FILEXREF.FEI
FILEXREF.MSG FILEXREF.WSL C:\DATA\MYREPORT.FIL
NOTE: Although the above is shown as two separate lines, you would
type it all in at the DOS prompt and press enter once.
NOTE: All parameters are positional. So, to override the last one,
we supplied the defaults for all others. That is, none may be
omitted prior to the one you wish to override.
Page 13
Notes and Restrictions
──────────────────────────────────────
1. The input files must be text files with each line terminated by a line
feed alone or a carriage return and line feed.
2. The FileXref utility distinguishes the comment syntax of each file
extension, i.e. REM in .BAT files and /* */ in C files. Words found
within comments are not cross referenced.
3. Words found in quotes or apostrophes are cross referenced.
4. If you get the message "Insufficient memory", try reducing the scope
of the processing. This may mean limiting the file specification list
(FSL) entries to only those files used by your application and/or
eliminating/limiting the word specification list (WSL) entries to just
those you need to see. Or see example 3 on page 11 for a multiple pass
solution.
5. Only the first 31 characters of a word are retained.
6. Cross reference entries will be created only for filenames and words
that are consistent with the symbol naming convention for each source
file type. So the restriction means that if the following is a
fragment from a .C file, a cross reference entry would not be created
for lines c or d below, even though these are valid DOS file names.
This is because the names are not valid C symbols.
a. avg_value = get_avg ( list ); OK
b. fp = fopen ( "C:\\TEST.dat", "r" ); OK
c. fp = fopen ( "87tax.dat", "w" ); starts with a digit
d. strcpy ( fspec, "A:$budget.trn" ); starts with $
Data File Formats
──────────────────────────────────────
FILEXREF.XRF Columns are quote and comma delimited.
Every line in FILEXREF.XRF consists of three columns.
COL COL COL
1 2 3
------ -------- ---
SYMBOL FILENAME Flags
Table 1: Export file flags
────────────────────────────────────────────────────
Column
123456
------
The symbol in the first column is:
1..... a filename.
.1.... a whole word.
..1... a word prefix.
...1.. an expansion of a word prefix.
....1. The symbol was referenced.
.....1 The symbol was marked for inclusion.
────────────────────────────────────────────────────
Page 14
Examples:
─────────────────────────────────────────────────────────────────
"SUB1","DRIVER","100011" Filename DRIVER contains a reference to
symbol SUB1, which is a filename.
"READ","DRIVER","010011" Filename DRIVER references the symbol
READ, which was specified as a word in
the word specification list.
"Testing","DOC1","001011" Filename DOC1 references the symbol
Testing, which is a word prefix in
the word specification list.
"Testing5","DOC1","000111" Filename DOC1 references the symbol
Testing5, which matches a word
prefix in the word specification
list.
─────────────────────────────────────────────────────────────────
FILEXREF.FEI Columns are quote and comma delimited.
Every line in FILEXREF.FEI consists of two columns.
COLUMN COLUMN
1 2
-------- -----
FILENAME Flags
Flags is as described on the prior page.
Examples:
───────────────────────────────────────────────────────────────────────
"SUB2","100001" Filename SUB2 was not referenced by any other file.
"EXEC","100001" Filename EXEC was not referenced by any other file.
───────────────────────────────────────────────────────────────────────
End of FileXref Documentation.